3. Components of Dynamics AX Services
Dynamics AX services come in two flavors:
document services and custom services. The following artifacts are part
of the implementation of both types of services:
Service implementation class An X++ class that implements the business logic encapsulated by a service. For example, the X++ class SalesSalesOrderService that comes with Dynamics AX 2009 is a service implementation class.
Service interface A child node of the Services
node in the Dynamics AX Application Object Tree (AOT). A service
interface includes properties, such as Namespace, Class, and
SecurityKey. For example, the AOT node SalesSalesOrderService (underneath the AOT node Services)
is a service interface. A valid service interface references a service
implementation class and exposes a subset of the methods of the service
implementation class as service operations.
Data object An X++ class, such as SalesSalesOrder, that can be used as a parameter for service operations.
Overview of Document Services
The term document services
stems from the reality that businesses need to exchange documents, such
as sales orders and invoices, with their partners. Document services
provide an external application interface. These services are built on
top of a query and provide a subset of create, read, update, delete,
find (CRUDF) service operations for a particular Axd<Document> type. The Axd<Document> represents a business entity.
Note
Document services are a subset of custom services. |
Document services provide document-centric
APIs—that is, APIs that operate on electronic documents. In Dynamics AX,
these documents are referred to as Axd<Documents> and are derived from Dynamics AX queries.
Examples of document-oriented APIs for a sales order service include create sales order, read sales order, update sales order, delete sales order, and find sales order.
Each of these APIs operates on an instance of a sales order document. Create sales order,
for example, takes a sales order document, persists it in the Dynamics
AX data store, and returns the sales order identifier for the persisted
instance.
Document Services Artifacts
All document services that come with Dynamics
AX 2009, as well as the ones you generate from Dynamics AX queries using
the Create New Document Service Wizard, include the following
artifacts:
Service contract Service-related metadata (no code) that is stored in AOT nodes, underneath the AOT node Services, such as SalesSalesOrderService.
Service contracts are not specific to document services and are also
used for custom services. The metadata includes the following
information:
Service implementation The code that exposes business logic. It mainly consists of the following elements:
Service implementation class An X++ class that derives from AifDocumentService
and implements the service operations that are published through the
service contract. There is one service implementation class for each
Dynamics AX service. For example, SalesSalesOrderService is the service implementation class for SalesSalesOrderService.
Axd<Document> class An X++ class that derives from AxdBase.
It primarily implements code for XML serialization, but it also
coordinates cross-table validation and cross-table defaulting. There is
one Axd<Document> class for each document service. For example, AxdSalesOrder is the Axd<Document> class for SalesSalesOrderService.
One or more Ax<Table> classes An Ax<Table> class is an X++ class that derives from AxInternalBase and implements validation, defaulting, and substitution logic for table fields. There is one Ax<Table> class for each table that is used in the query that is used to generate the Dynamics AX document service. For example, AxSalesTable and AxSalesLine are two Ax<Table> classes that have been generated for the SalesSalesOrderService.
Data object
An X++ class that represents a parameter type. The parameter types that
the Create New Document Service Wizard generates derive from AifDocument represent business documents. For example, SalesSalesOrder is the data object that is created for the SalesSalesOrderService.
You can find a complete list of document
services artifacts in the AIF documentation in the Microsoft Dynamics AX
2009 SDK on MSDN.
Axd<Document> Classes
Axd<Document> classes (e.g., AxdSalesOrder) derive from the X++ class AxdBase and are generated from Dynamics AX queries. Axd<Document>
classes provide default implementations for the XML serialization of
used data objects as well as hooks for validation code. Axd<Document> classes also call Ax<Table> classes to perform value mapping and can filter data.
Axd<Document>
classes derive XML schema definitions used for XML serialization
directly from the structure of the underlying query; all generated
schema definitions comply with principles described in the Reference
Model for Service Oriented Architecture 1.0 mentioned earlier in the
chapter. The generated XML serialization code leverages Dynamics AX
concepts such as extended data types (EDTs) to further restrict valid XML schemas and improve XML schema validation. During serialization, Axd<Document> classes use Ax<Table> classes to persist data to tables and to read from tables. Because Ax<Table> classes implement business logic such as defaulting and value mapping, Axd<Document> classes never bypass Ax<Table> classes to access tables directly.
Figure 2 illustrates the mapping between a Dynamics AX query used for the Axd<Document> class Axd<Document> and the generated XML schema definition.
Axd<Document>
classes also provide an API for orchestrating cross-table validation
and defaulting. Validation and defaulting logic that is relevant only
for a specific document service can also be implemented in Axd<Document> classes, such as by using the methods prepareForSave, prepareForUpdate, and prepareForDelete.
The AifEntityKey
class is used for all service operations that require one or more
specific records. It is also used for the return values for service
operations of type create. An AifEntityKey
instance uniquely identifies an entity. It consists of a table
identifier (ID), the field IDs for a unique index of that table, and the
values of the respective fields. In addition, it holds the record ID of
the retrieved records. The following code shows a partial
implementation from the AxdBaseCreate class.
protected void setEntityKey()
{
Map keyData;
;
keyData = SysDictTable::getKeyData(axBcStack.top().currentRecord());
entityKey = AifEntityKey::construct();
entityKey.parmTableId(axBcStack.top().currentRecord().TableId);
entityKey.parmRecId(axBcStack.top().currentRecord().RecId);
entityKey.parmKeyDataMap(keyData);
// More code lines go here.
}
|
Ax<Table> Classes
Ax<Table> classes (e.g., AxSalesTable and AxSalesLine) derive from the X++ class AxInternalBase. There is one Ax<Table> class for each table that is used in a document service. More specifically, the same Ax<Table> class is used by Axd<Document> classes that are based on queries referencing the same table. Here are some uses of Ax<Table> classes:
Help implement defaulting scenarios,
such as automatically changing a table field when a related table field
is changed. For example, an Ax<Table> class can automatically update or reset the table field Delivery Address when the related Sales Order table field,
Customer Account, is changed.
Keep
track of the defaulting state of table fields. For example, when a
Dynamics AX user sets a specific table field explicitly, the defaulting
logic must not overwrite the explicitly set value.
Implement
validation logic for table fields, value substitution, and logic for
fetching numbers or identifiers from number sequences.
Implement parm methods for fields on the underlying table.
Note
Ax<Table> classes are frequently referred to as AxBC classes, both in code and in documentation. |
Document Services Use Cases
The standard create, read, update, delete
(CRUD) service operations for document services are particularly useful
and efficient in business-to-business (B2B) scenarios or in offline
integration scenarios in which communication between systems is
unreliable and slow and changes to documents occur infrequently.
Document services are also useful for
integrating Dynamics AX with systems through the exchange of
coarse-grained business documents, such as sales orders and leads. This
type of data exchange is commonly used in the following scenarios:
Exchanged data is transacted. For
example, if a request to create a sales order fails, the state of the
Dynamics AX database must remain unchanged. No side-effects must occur:
artifacts such as address or customer records that were created as part
of the processing of the failed request must not be left; instead, the
entire transaction must be rolled back.
Data
exchanges are expensive because, for example, the request and response
messages are exchanged through the Internet. Coarse-grained data
exchange in the form of business documents can help reduce the number of
exchanged messages.
The response
time—that is, the time between sending the request (e.g., to create a
sales order) to Dynamics AX and receiving a response—isn’t critical.
In addition to their use in B2B integration
scenarios, coarse-grained document services are helpful in
application-to-application (A2A) integration scenarios, such as when
you’re integrating Dynamics AX with certain document-centric Microsoft
Office products.
Document Service Development Tools
Although you can create document services
manually, we don’t recommend it. Instead, you should use the Create New
Document Service Wizard to quickly generate new document services from
AOT queries and the Update Document Service form to update existing
document services. You can find this wizard and form at
Tools\Development Tools\ Application Integration Framework.
Dynamics AX 2009 also includes more than 50 ready-to-use document services. These include services such as SalesOrderService and CustomerService. You can find a complete list of these built-in services in the AOT Services node at design time or through the AIF Services Administration form at run time.
You can also extend out-of-the-box services
with more fine-grained custom service operations, such as updating the
delivery address for a specific sales order.
Overview of Custom Services
Custom services
can provide any kind of API. Even so, you should never use custom
services to replace document services, and you should not use them to
implement CRUD functionality for query-based entities. Instead, you
should be use custom services to implement functionality that can’t be
directly tied to a Dynamics AX query, such as when you want to stop
payment on a check or start an invoice approval process.
Custom Service Use Cases
Custom services are indispensible in A2A
scenarios in which systems are tightly integrated and small chunks of
data need to be exchanged efficiently between external applications and
Dynamics AX. Examples of such applications are interactive applications
that manipulate data managed in Dynamics AX, such as Microsoft Office
Business Applications (OBAs).
Custom Services Development
Dynamics AX 2009 doesn’t provide wizards or
other tools for implementing custom services. Instead, custom services
must follow certain rules, which we cover in the following section.
Note
Although
the design-time experience for document and custom services differs,
both service types are configured and published in the same way. |
